Troubleshooting and FAQ

**Referenced Files in This Document** - [README.md](file://README.md) - [package.json](file://package.json) - [.eleventy.js](file://.eleventy.js) - [worker.js](file://worker.js) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [netlify.toml](file://netlify.toml) - [src/assets/js/main.js](file://src/assets/js/main.js) - [src/assets/js/modules/search-functionality.js](file://src/assets/js/modules/search-functionality.js) - [src/assets/js/modules/navigation.js](file://src/assets/js/modules/navigation.js) - [src/assets/js/modules/theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [src/assets/css/main.css](file://src/assets/css/main.css) - [src/assets/css/modules/25-responsive-tablet-max-width-1024px.css](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css) - [src/assets/css/modules/26-responsive-mobile-max-width-900px.css](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css) - [src/assets/css/modules/41-search-modal.css](file://src/assets/css/modules/41-search-modal.css) - [src/alliance-login.njk](file://src/alliance-login.njk) - [src/_data/site.json](file://src/_data/site.json)

Introduction

This document provides comprehensive troubleshooting guidance and a focused FAQ for the Ace Strategies Prime platform. It covers development environment setup, CMS authentication, member portal access, deployment errors, JavaScript module debugging, CSS styling issues, template rendering problems, performance troubleshooting (including slow page loads, search indexing, and Cloudflare Worker performance), browser compatibility and mobile responsiveness, error messages and resolutions, and operational guidance for logs, monitoring, and performance bottlenecks.

Project Structure

The platform is an Eleventy 3 static site with a Cloudflare Worker runtime, Sveltia CMS for Git-backed content editing, and Pagefind for client-side search. The build pipeline produces a static site served by Cloudflare Workers, with the Worker handling authentication, OAuth, and APIs.

graph TB
Dev["Developer Machine"] --> Eleventy["Eleventy Build<br/>_site output"]
Dev --> Worker["Cloudflare Worker<br/>worker.js"]
Eleventy --> Site["_site/<br/>Static assets + Pagefind"]
Worker --> Site
Browser["Browser"] --> Worker
Worker --> Site
Worker --> Resend["Resend API"]
Worker --> Sheets["Google Sheets API"]

Diagram sources

[README.md:556-587](file://README.md#L556-L587)
[worker.js:1-321](file://worker.js#L1-L321)
[.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Section sources

[README.md:80-156](file://README.md#L80-L156)
[package.json:1-32](file://package.json#L1-L32)
[.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Core Components

Eleventy static site generation with transforms, filters, collections, and passthrough copies.
Cloudflare Worker for authentication, OAuth, and APIs.
Sveltia CMS for content editing at /admin/.
Pagefind for client-side search indexing during build.
Responsive CSS split into modular files with breakpoint-specific overrides.

Section sources

[.eleventy.js:1-283](file://.eleventy.js#L1-L283)
[worker.js:1-321](file://worker.js#L1-L321)
[README.md:174-204](file://README.md#L174-L204)
[README.md:556-587](file://README.md#L556-L587)

Architecture Overview

The runtime architecture routes unmatched requests to the Worker, which serves auth-gated pages and APIs, while static assets are served from the built site.

sequenceDiagram
participant U as "User"
participant W as "Cloudflare Worker"
participant A as "ASSETS (_site)"
participant R as "Resend API"
participant G as "Google Sheets API"
U->>W : Request /alliance/members/*
W->>W : Read ace_member_session cookie
alt Valid session
W->>A : Fetch static asset
A-->>U : HTML/CSS/JS
else No/invalid
W-->>U : Redirect to /alliance/login/?next=...
end
U->>W : POST /alliance/login/ (email)
W->>W : Check MEMBER_EMAILS
alt Approved
W->>R : Send magic link email
end
W-->>U : Redirect to /alliance/login/?sent=1
U->>W : GET /alliance/verify/?token=...
W->>W : Lookup token in MAGIC_TOKENS
alt Valid
W-->>U : Set ace_member_session cookie + redirect to /alliance/members/
else Expired/Invalid
W-->>U : Redirect to /alliance/login/?error=expired
end
U->>W : GET /api/polling.json
W->>G : Fetch polling data
G-->>W : JSON
W-->>U : JSON (with caching headers)

Diagram sources

[worker.js:78-177](file://worker.js#L78-L177)
[worker.js:230-276](file://worker.js#L230-L276)
[README.md:638-653](file://README.md#L638-L653)

Detailed Component Analysis

Authentication and Member Portal

Common issues include missing secrets, KV namespaces, invalid tokens, and email deliverability.

flowchart TD
Start(["Login Flow"]) --> CheckKV["KV namespaces bound?"]
CheckKV --> |No| KVError["Show 503 KV not configured"]
CheckKV --> |Yes| ParseForm["Parse form data"]
ParseForm --> Honeypot{"Honeypot filled?"}
Honeypot --> |Yes| BotRedirect["Redirect with sent=1"]
Honeypot --> |No| ValidateEmail{"Valid email?"}
ValidateEmail --> |No| BadEmail["Redirect with error=email"]
ValidateEmail --> |Yes| CheckApproved["Lookup MEMBER_EMAILS"]
CheckApproved --> |Not approved| SilentNoop["Redirect with sent=1"]
CheckApproved --> |Approved| IssueToken["Generate token + store in MAGIC_TOKENS"]
IssueToken --> SendEmail["POST to Resend API"]
SendEmail --> Done(["Redirect with sent=1"])

Diagram sources

[worker.js:94-147](file://worker.js#L94-L147)
[worker.js:70-75](file://worker.js#L70-L75)

Section sources

[worker.js:70-147](file://worker.js#L70-L147)
[README.md:425-477](file://README.md#L425-L477)

Search Functionality (Pagefind)

Issues commonly involve Pagefind not loading, search results not appearing, or keyboard navigation failing.

flowchart TD
Init(["initSearch"]) --> LoadPF["Load /pagefind/pagefind.js"]
LoadPF --> PFReady{"Loaded?"}
PFReady --> |No| Warn["Console warn, show 'Search unavailable'"]
PFReady --> |Yes| Open["Open modal, focus input"]
Open --> Input["User types (debounced 200ms)"]
Input --> QueryLen{"Length ≥ 2?"}
QueryLen --> |No| Placeholder["Show placeholder"]
QueryLen --> |Yes| PFSearch["pf.search(query)"]
PFSearch --> Results{"Results?"}
Results --> |No| NoResults["Show 'No results found'"]
Results --> |Yes| Render["Render up to 10 results"]
Render --> Nav["Keyboard navigation (↑/↓/Enter)"]
Nav --> ESC{"Escape?"}
ESC --> |Yes| Close["Close modal"]
ESC --> |No| Stay["Keep modal open"]

Diagram sources

[src/assets/js/modules/search-functionality.js:1-179](file://src/assets/js/modules/search-functionality.js#L1-L179)

Section sources

[src/assets/js/modules/search-functionality.js:1-179](file://src/assets/js/modules/search-functionality.js#L1-L179)
[README.md:556-587](file://README.md#L556-L587)

Navigation and Accessibility

Mobile menu issues often relate to focus trapping, click-outside behavior, and ARIA attributes.

Section sources

[src/assets/js/modules/navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)
[src/assets/css/modules/25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
[src/assets/css/modules/26-responsive-mobile-max-width-900px.css:1-358](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L1-L358)

Theme Toggling and CSS Modules

Theme switching relies on intersection observers to toggle body classes per themed sections.

Section sources

[src/assets/js/modules/theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
[src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)

Polling API (Google Sheets)

Errors surface as 503 when secrets are missing or network errors when fetching sheets.

Section sources

[worker.js:230-276](file://worker.js#L230-L276)
[README.md:357-362](file://README.md#L357-L362)

Dependency Analysis

Build-time dependencies: Eleventy, Pagefind, html-minifier-terser, sharp, wrangler.
Runtime dependencies: Cloudflare Worker runtime, Pagefind client library, optional GSAP/ScrollTrigger for animations.
External services: Resend (magic link emails), Google Sheets (polling data).

graph LR
Pkg["package.json scripts"] --> Eleventy["Eleventy build"]
Pkg --> Pagefind["Pagefind indexing"]
Eleventy --> Site["_site/"]
Pagefind --> Site
Worker["worker.js"] --> Resend["Resend API"]
Worker --> Sheets["Google Sheets API"]

Diagram sources

[package.json:5-12](file://package.json#L5-L12)
[.eleventy.js:6-14](file://.eleventy.js#L6-L14)
[worker.js:123-143](file://worker.js#L123-L143)

Section sources

[package.json:1-32](file://package.json#L1-L32)
[.eleventy.js:1-283](file://.eleventy.js#L1-L283)
[worker.js:1-321](file://worker.js#L1-L321)

Performance Considerations

Static assets: Leverage long-lived caching for immutable assets and short-lived caching for dynamic content.
Search: Pagefind indexing occurs at build time; ensure builds complete successfully to avoid degraded search UX.
Worker cold starts: Keep the Worker minimal; offload heavy tasks to external APIs.
Animations: Optional GSAP/ScrollTrigger; if not present, core functionality remains intact but animations are skipped.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Development Environment Setup

Symptoms

npm install fails or dev server does not start.
Live reload not triggering on CSS/JS changes.

Root causes and fixes

Node.js and npm versions: Ensure Node.js ≥ 18 and npm ≥ 9 as per prerequisites.
Wrangler CLI: Authenticate and ensure wrangler login succeeds.
Watch targets: Eleventy watches src/assets/css/, src/assets/js/, and src/_data/—ensure changes occur under these directories.
Port conflicts: The Eleventy dev server runs on port 8080; change if in use.

Verification steps

Run npm install and confirm no peer dependency warnings.
Run npm start and verify http://localhost:8080 loads.
Run npm run dev:cms and verify CMS at http://localhost:4001.

Section sources

[README.md:47-77](file://README.md#L47-L77)
[.eleventy.js:16-22](file://.eleventy.js#L16-L22)

CMS Authentication Failures

Symptoms

Sveltia CMS login fails or shows OAuth errors.
CORS preflights fail for CMS auth.

Root causes and fixes

OAuth proxy: Sveltia CMS uses a hosted OAuth proxy; ensure the origin matches the site domain.
CORS preflight: The Worker responds to OPTIONS with appropriate headers for CMS auth.
Legacy OAuth endpoints: The Worker exposes legacy GitHub OAuth endpoints for Sveltia CMS; ensure correct client credentials are configured.

Verification steps

Confirm the CMS entry point at /admin/ and that the OAuth callback URL is correct.
Check browser Network panel for OPTIONS preflight success.
Verify that the legacy OAuth endpoints are reachable and return expected HTML.

Section sources

[README.md:174-204](file://README.md#L174-L204)
[worker.js:183-227](file://worker.js#L183-L227)

Member Portal Access Issues

Symptoms

Redirect loop to /alliance/login/.
Magic link not received or expired immediately.
“Check your email” shown regardless of membership status.

Root causes and fixes

KV namespaces: MEMBER_EMAILS and MAGIC_TOKENS must be created and bound in wrangler.jsonc.
Secrets: SESSION_SECRET and RESEND_API_KEY must be set; missing secrets cause 503 responses.
Email deliverability: Ensure the sending domain is configured and not blocked by spam filters.
Token lifecycle: Tokens expire after 15 minutes; ensure users act promptly.
Member enumeration: The Worker intentionally returns the same “check your email” message for both unapproved and non-existent emails.

Verification steps

Confirm KV namespace creation and binding IDs in wrangler.jsonc.
Verify secret keys are set via wrangler secret put.
Add a test member via wrangler kv:key put and attempt login.
Inspect browser cookies for ace_member_session after successful verification.

Section sources

[README.md:425-477](file://README.md#L425-L477)
[worker.js:70-75](file://worker.js#L70-L75)
[worker.js:94-147](file://worker.js#L94-L147)
[worker.js:150-177](file://worker.js#L150-L177)

Deployment Errors

Symptoms

Build fails with Pagefind errors.
Preview or deploy hangs or returns Worker errors.

Root causes and fixes

Build script: npm run build invokes Eleventy and Pagefind; ensure both succeed.
Preview: npm run preview builds and runs via wrangler dev; check for Worker route mismatches.
Deployment: npm run deploy builds and deploys via wrangler; ensure credentials and bindings are present.

Verification steps

Run npm run build locally and inspect _site/ and _site/pagefind/.
Run npm run preview and verify static assets and Worker routes.
Run npm run deploy and monitor Cloudflare dashboard for build logs.

Section sources

[package.json:5-12](file://package.json#L5-L12)
[README.md:556-587](file://README.md#L556-L587)

JavaScript Module Debugging

Symptoms

Navigation menu does not open/close.
Search modal does not appear or results do not load.
Theme toggling not applied.

Root causes and fixes

Navigation: Ensure DOM elements with selectors .nav-toggle and .nav-menu exist; verify event listeners attach.
Search: Confirm Pagefind loader is invoked; check console for “Pagefind not available”; ensure /pagefind/pagefind.js is present in _site/.
Theme toggling: Verify sections with data-theme exist and IntersectionObserver is supported.

Debugging techniques

Use browser DevTools Console to check for warnings and errors.
Temporarily disable optional animations (GSAP/ScrollTrigger) to isolate core functionality.
Add targeted console logs around module initialization.

Section sources

[src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)
[src/assets/js/modules/navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)
[src/assets/js/modules/search-functionality.js:1-179](file://src/assets/js/modules/search-functionality.js#L1-L179)
[src/assets/js/modules/theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)

CSS Styling Issues

Symptoms

Styles not applied or overridden unexpectedly.
Mobile layout broken at specific breakpoints.

Root causes and fixes

CSS import order: Ensure main.css imports modules in the intended cascade.
Breakpoints: Tablet (max-width: 1024px) and mobile (max-width: 900px) styles override desktop defaults.
Search modal: Ensure .search-modal and related elements exist; verify theme-aware overrides.

Debugging techniques

Inspect computed styles in DevTools; verify specificity and cascade order.
Toggle responsive device toolbar and step through breakpoint-specific rules.
Temporarily comment out module imports to isolate problematic styles.

Section sources

[src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)
[src/assets/css/modules/25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
[src/assets/css/modules/26-responsive-mobile-max-width-900px.css:1-358](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L1-L358)
[src/assets/css/modules/41-search-modal.css:1-314](file://src/assets/css/modules/41-search-modal.css#L1-L314)

Template Rendering Problems

Symptoms

Obsidian wikilinks or callouts not rendered.
Unexpected HTML minification issues.

Root causes and fixes

Obsidian syntax transform: Ensure obsidianSyntax transform is active for HTML output; verify frontmatter and content formatting.
HTML minification: Enabled in production; verify that minification does not break semantic markup.

Verification steps

Check that generated HTML contains expected anchor tags and callout wrappers.
Compare development vs production builds for differences.

Section sources

[.eleventy.js:216-239](file://.eleventy.js#L216-L239)
[.eleventy.js:241-261](file://.eleventy.js#L241-L261)

Performance Troubleshooting

Symptoms

Slow page loads.
Search results delayed or not available.
Cloudflare Worker latency spikes.

Root causes and fixes

Static assets: Confirm long-term caching headers for immutable assets and short-term caching for dynamic content.
Search: Ensure Pagefind indexing completes during build; verify _site/pagefind/ presence.
Worker: Reduce synchronous work; rely on external APIs; monitor cold start behavior.

Monitoring tips

Use browser DevTools Network panel to inspect asset caching and response times.
Monitor Cloudflare Workers logs for latency and error rates.

Section sources

[netlify.toml:14-26](file://netlify.toml#L14-L26)
[README.md:556-587](file://README.md#L556-L587)
[worker.js:230-276](file://worker.js#L230-L276)

Browser Compatibility and Mobile Responsiveness

Symptoms

Navigation menu not accessible via keyboard.
Search modal not usable on small screens.
Theme toggle not applied on section transitions.

Root causes and fixes

Focus trapping and ARIA: Navigation module sets aria-expanded and manages focus; ensure DOM structure matches selectors.
Mobile viewport: Breakpoint-specific CSS adjusts layout and typography; verify meta viewport and media queries.
IntersectionObserver: Theme toggling requires modern browsers; provide graceful degradation.

Section sources

[src/assets/js/modules/navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)
[src/assets/js/modules/theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
[src/assets/css/modules/25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
[src/assets/css/modules/26-responsive-mobile-max-width-900px.css:1-358](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L1-L358)

Error Message References and Solutions

“Member auth KV namespaces not yet configured”: Ensure MEMBER_EMAILS and MAGIC_TOKENS are created and bound in wrangler.jsonc; set SESSION_SECRET and RESEND_API_KEY.
“Service misconfigured” (polling API): Set GOOGLE_SHEETS_ID and GOOGLE_SHEETS_API_KEY; verify API permissions.
“Check your email” shown regardless of membership: Intentional to prevent member enumeration; verify MEMBER_EMAILS entry exists.
“Pagefind not available”: Confirm Pagefind WASM and JS are present in _site/pagefind/; ensure search module initializes.

Section sources

[worker.js:70-75](file://worker.js#L70-L75)
[worker.js:244-246](file://worker.js#L244-L246)
[worker.js:115-116](file://worker.js#L115-L116)
[src/assets/js/modules/search-functionality.js:20-28](file://src/assets/js/modules/search-functionality.js#L20-L28)

Accessing Logs, Monitoring Health, and Identifying Bottlenecks

Cloudflare Workers: Use Wrangler CLI to view logs and monitor performance metrics in the Cloudflare dashboard.
Static assets: Confirm cache headers and asset integrity in the Network panel.
CMS: Validate OAuth preflight responses and CORS headers.

Section sources

[README.md:556-587](file://README.md#L556-L587)
[netlify.toml:14-26](file://netlify.toml#L14-L26)

Conclusion

This guide consolidates actionable troubleshooting steps and FAQs for the Ace Strategies Prime platform. By validating environment setup, secrets, KV namespaces, and build outputs—and by leveraging browser dev tools and Cloudflare dashboards—you can quickly diagnose and resolve most issues. For persistent problems, consult the referenced sections and files for precise configuration and behavior details.

Appendices

Frequently Asked Questions (FAQ)

Q: Why am I seeing “Member auth KV namespaces not yet configured”? A: MEMBER_EMAILS and MAGIC_TOKENS KV namespaces are missing or not bound. Create them via wrangler and add the IDs to wrangler.jsonc, then redeploy.

Q: How do I add or remove IAA members? A: Use wrangler kv:key put/delete commands against the MEMBER_EMAILS namespace. List members with a list operation.

Q: Why is my search not working? A: Ensure Pagefind indexed content during build and that /pagefind/pagefind.js is present in _site/pagefind/. Check console for “Pagefind not available”.

Q: How do I enable the contact form? A: Replace the placeholder access key in the contact form template with your Web3Forms key.

Q: What Node.js and npm versions are required? A: Node.js ≥ 18 and npm ≥ 9. Ensure your local environment matches these versions.

Q: How do I preview the production build locally? A: Run npm run preview to build and run via wrangler dev, mirroring production behavior.

Q: How do I configure custom domains? A: Add your domain in the Cloudflare dashboard under Workers & Pages for the project and point it to the Worker.

Q: Why is the polling data endpoint returning an error? A: Set GOOGLE_SHEETS_ID and GOOGLE_SHEETS_API_KEY secrets and ensure the spreadsheet is readable by the API key.

Q: How do I manage Sveltia CMS content? A: Visit /admin/, sign in with GitHub, and edit content in the collections listed in the documentation.

Q: How do I fix mobile navigation accessibility issues? A: Ensure .nav-toggle and .nav-menu elements exist and that the navigation module runs on DOMContentLoaded.

Q: How do I verify search keyboard shortcuts? A: Press Ctrl/Cmd + K to open the search modal; use arrow keys and Enter to navigate results.

Section sources

[README.md:47-77](file://README.md#L47-L77)
[README.md:465-477](file://README.md#L465-L477)
[README.md:480-494](file://README.md#L480-L494)
[README.md:523-554](file://README.md#L523-L554)
[README.md:556-587](file://README.md#L556-L587)
[README.md:656-665](file://README.md#L656-L665)
[src/assets/js/modules/search-functionality.js:170-176](file://src/assets/js/modules/search-functionality.js#L170-L176)
[src/assets/js/modules/navigation.js:48-75](file://src/assets/js/modules/navigation.js#L48-L75)

Troubleshooting and FAQ

Table of Contents

Introduction

Project Structure

Core Components

Architecture Overview

Detailed Component Analysis

Authentication and Member Portal

Search Functionality (Pagefind)

Navigation and Accessibility

Theme Toggling and CSS Modules

Polling API (Google Sheets)

Dependency Analysis

Performance Considerations

Troubleshooting Guide

Development Environment Setup

CMS Authentication Failures

Member Portal Access Issues

Deployment Errors

JavaScript Module Debugging

CSS Styling Issues

Template Rendering Problems

Performance Troubleshooting

Browser Compatibility and Mobile Responsiveness

Error Message References and Solutions

Accessing Logs, Monitoring Health, and Identifying Bottlenecks

Conclusion

Appendices

Frequently Asked Questions (FAQ)